﻿using System;

namespace Sgr.Domain.Uow.Database
{
    /// <summary>
    /// 数据库API容器接口
    /// </summary>
    /// <remarks>
    /// 该接口提供数据库API的管理功能，包括：
    /// 1. 查找已注册的数据库API
    /// 2. 添加新的数据库API
    /// 3. 获取或按需创建数据库API
    /// </remarks>
    public interface IDatabaseApiContainer
    {
        /// <summary>
        /// 查找指定键的数据库API
        /// </summary>
        /// <param name="key">数据库API的唯一标识键</param>
        /// <remarks>
        /// 如果指定的键不存在，则返回null
        /// </remarks>
        /// <returns>找到的数据库API实例，如果未找到则返回null</returns>
        IDatabaseApi? FindDatabaseApi(string key);

        /// <summary>
        /// 添加数据库API到容器中
        /// </summary>
        /// <param name="key">数据库API的唯一标识键</param>
        /// <param name="api">要添加的数据库API实例</param>
        /// <remarks>
        /// 如果指定的键已存在，则抛出异常
        /// </remarks>
        void AddDatabaseApi(string key, IDatabaseApi api);

        /// <summary>
        /// 获取指定键的数据库API，如果不存在则使用工厂方法创建
        /// </summary>
        /// <param name="key">数据库API的唯一标识键</param>
        /// <param name="factory">用于创建新数据库API实例的工厂方法</param>
        /// <remarks>
        /// 此方法确保返回一个有效的数据库API实例：
        /// 1. 如果指定键的API已存在，则返回现有实例
        /// 2. 如果不存在，则使用工厂方法创建新实例并添加到容器中
        /// </remarks>
        /// <returns>获取到的或新创建的数据库API实例</returns>
        IDatabaseApi GetOrAddDatabaseApi(string key, Func<IDatabaseApi> factory);
    }
}